package lumis.portal.filesystem;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;

import lumis.portal.stability.StableMinor;

/**
 * Provides operations for manipulating the file system.
 * 
 * @depend - processes - PortalFile
 * 
 * @version $Revision: 13082 $ $Date: 2011-05-27 16:03:12 -0300 (Fri, 27 May 2011) $
 * @since 4.1.0
 */
@StableMinor(version = "6.0", sinceVersion = "4.1")
public interface IFileSystemManager
{
	/**
	 * Locks a file for reading operations. This lock is obeyed only by threads
	 * in the same JVM that also use a lock method available in this manager.
	 * <p>
	 * Many threads may acquire read locks simultaneously, but if a thread 
	 * acquire a write lock for a file, no other thread can acquire any lock.
	 * If the file is already locked anyway that this thread cannot acquire 
	 * the lock, it is blocked until the lock can be acquired. 
	 * <p>
	 * {@link #unlockFileForRead(File)} must be executed after this method. A
	 *  try/finally block should be used in order to guarantee this.
	 * @param file the file to be locked.
	 * @see #unlockFileForRead(File)
	 * @see #lockFileForWrite(File)
	 * @since 4.1.0
	 */
	public void lockFileForRead(File file);
	
	/**
	 * Unlocks a file locked by {@link #lockFileForRead(File)}.
	 * @param file the file to be unlocked.
	 * @see #lockFileForRead(File)
	 * @since 4.1.0
	 */
	public void unlockFileForRead(File file);
	
	/**
	 * Locks a file for writing operations. This lock is obeyed only by threads
	 * in the same JVM that also use a lock method available in this manager.
	 * <p>
	 * Many threads may acquire read locks simultaneously, but if a thread 
	 * acquire a write lock for a file, no other thread can acquire any lock.
	 * If the file is already locked anyway that this thread cannot acquire 
	 * the lock, it is blocked until the lock can be acquired. 
	 * <p>
	 * {@link #unlockFileForWrite(File)} must be executed after this method. A
	 *  try/finally block should be used in order to guarantee this.
	 * @param file the file to be locked.
	 * @see #unlockFileForWrite(File)
	 * @see #lockFileForRead(File)
	 * @since 4.1.0
	 */
	public void lockFileForWrite(File file);
	
	/**
	 * Unlocks a file locked by {@link #lockFileForWrite(File)}.
	 * @param file the file to be unlocked.
	 * @see #lockFileForWrite(File)
	 * @since 4.1.0
	 */
	public void unlockFileForWrite(File file);

	/**
	 * Writes content in the specified file. The change is replicated across
	 * the cluster.
	 * @param file the file to write. If it already exists it is 
	 * overwritten.
	 * @param content the content.
	 * @since 4.1.0
	 */
	public void writeFile(PortalFile file, byte[] content) throws IOException;
	
	/**
	 * Writes content in the specified file. The change is replicated across
	 * the cluster.
	 * @param file the file to write. If it already exists it is 
	 * overwritten.
	 * @param content the content.
	 * @since 4.1.0
	 */
	public void writeFile(PortalFile file, InputStream content) throws IOException;
	
	/**
	 * Performs a file copy. The copy operation is repeated across
	 * the cluster.
	 * @param source the source file.
	 * @param destination the destination file. If it already exists it is 
	 * overwritten.
	 * @since 4.1.0
	 */
	public void copyFile(PortalFile source, PortalFile destination) throws IOException;
}